Resources can be either sounds ('snd ', in 'sfil' files), pictures ('PICT') or movies (in 'MooV' files), but must be stored in files saved on disc. It also can present short text items without the need to create PICTs (in the font, size, style and color specified using the Stimulus Text button at the top of the Script Editor window). Resource files should be created in some other application before trying to display them in MacStim! Any combination of these is theoretically possible, and sounds can merge into the next picture stimulus, though movies are independent. You must have 32-bit Color QuickDraw and QuickTime installed in your system to display the movies. PICTs and sounds are prepared for rapid presentation by pre-loading them into memory (though you can prevent this for individual pictures so they are loaded on-the-fly). If there is not enough memory, MacStim will tell you before letting the experiment run, so you can try to fix it before you start. It uses offscreen graphics worlds and QuickTime 1.6 or higher if you wish to display movies. Animations are simple and can re-use the same picture which you can offset from the center using horizontal and vertical offsets.
2. MacStim uses a "script":
A script (text in a text editor) contains the information MacStim requires to present the resources in the correct order and duration. The script, once created, must be saved in the same folder as the resources ("stimuli") it uses. MacStim assumes this relationship, and will not begin the experiment if any specified files are not found. The script also specifies what type of subject input is needed for it to record a response, eg none, a mouse click or key press (or add-on board trigger or serial port signal). The script is like a play's script, in that it directs the flow of resources and timing used in any given MacStim experiment. MacStim reads scripts from left to right, top to bottom. Blank lines or lines with a parenthesis ("{") at the start are ignored & can be used for script comments (shortcut is Command-[ to comment a line, Command-] to uncomment a line, where MacStim uses the line(s) in which the cursor or the selection exists). You can put text into the script editor either by:
(i) typing directly, or
(ii) using the Resource Finder (see below) or
(iii) opening up text files created and saved earlier by double clicking them in the Finder or using the File menu commands in MacStim. The Preferences (under the File menu) are extremely important to unleash to power of MacStim! These control the settings for an experiment's display, resources, reaction time recording and much much more! The currently set global experiment preferences (see Preferences topic) are also saved in a script when it is saved, so that opening it later will reset to these preferences again (aiming to save time when starting experiments which have been finely tuned on a previous occasion), as will clicking on a script when multiple ones are concurrently open. These actions do not reset the monitors if they were different in the scripts since this is very confusing. Checks for the script's version compatibility, add-on board settings correctness, etc are also performed.
3. Scripts contain "trials":
Each line (ending with a carriage return) in a script is called a "trial" (except for comment lines). There are 4 trial types, specified by their type (or the first letter of the type name), which are treated slightly differently by MacStim:
(i) SINGLE: are single trials specifying all necessary information on a single line (abbrev: "S", "s").
(ii) BLOCK: trials are members of a group of trials on consecutive lines, which are to be considered together eg as an animation block, with the order remaining constant from top to bottom (abbrev: "B" or "b"). A block can be executed repetitively for a specified time interval in the first of the block.
(iii) RANDOM: trials are members of a group whose order is to be randomized every time the whole block is executed (abbrev: "R" or "r"). Note that random trials are very special, in that they can have "subtrials". These allow blocks of grouped trials whose order is to remain internally consistent to be randomized!
(iv) PAUSE: trials will only advance to the next part of the trial after a specified user action (mouse click, key press) or trigger event (serial port character or add-on board trigger) occurs (abbrev: "P" or "p"). These are useful to pause whilst certain experimental conditions are adjusted, or can allow the whole experiment to be coordinated by an external influence (this is not an 'X' files pun). Note that you must move through all phases of a trial to get completely past a pause trial (which means at least 3 of the specified user or trigger actions, see under Experiments).
(v) CONTINUOUS: trials are like infinite single trials which will play the background and stimulus resources according to the times requested continually until an event specified as a stop event is detected. The trial will then cease and the next one commenced. These are useful as dynamic pause trials eg to show alternating background and foreground resources for an indeterminate period.
4. Trials contain "fields":
Each trial contains tab-separated fields which are used to specify the trial type, resource types, their duration, order and file names, and the event to look for before recording a reaction time. A field header comment line can assist in remembering the order of the fields, and can be added using the Insert Header Line menu item (Command-L) in the Control menu. All timing is done in microseconds (system 7 & above) or ticks (pre-system 7). The following example shows all the field headers and one example of their format:
{ type num pre max tot rep stpEvt bg st bg-file st-file
s 1 1.0 3.0 5.0 10.0 m p p picture1 picture2
(1) "type" is the trial type as above, "s" means a single trial
(2) "num" is the number of subtrials to use attached to this trial, and is ignored in all but random trial types
(3) "pre" is the initial delay in seconds before the stimulus is presented. If you want a background resource to be shown/sounded during this time (eg a background PICT) then make this time greater than zero. Please note that most scripts will work best if this time is not zero.
(4) "max" is the maximum time in seconds to show the stimulus.
(5) "tot" is the total seconds for this trial. If this total time is greater than "pre + max" then the background resource will be presented again to make up the total time of the trial. In the example above, the background resource ("picture1") will be re-presented for 1 second at least. I say at least, since if the subject clicks the mouse (the "stpEvt") before the max time of 3 secs, then the remaining max time will be also be used to show the background picture until the total of tot secs passes. tot can be zero, which will cause the pre and max times only to present stimuli.
(6) "rep" is the number of seconds for which the trial should be repeated, ie 10 secs in the above example. This trial would play twice before moving onto the next trial in the script. If (rep < pre + max) or (rep < tot), rep is effectively 0 secs. For random & block trial types, the leading trial rep time determines the repetition time of the whole block. For continuous trials this field is ignored (and effectively a long time).
NOTE: negative times for any of these time periods, tell MacStim to choose a random time from 0 seconds to the limit of the number on the fly. Also, in v2.1.8 and above, very accurate timing is used (to within 20 microseconds absolute time) and in practical terms times less than 50 milliseconds will not usually have time to present a stimulus (unless it is nothing!).
(7) "stpEvt" is the event required to trigger recording of the reaction time (m mouse down, k key down, v voice activation (vox), t board triggered, s serial port character, n nothing ie ignore all event types).
(8) "bg" is the background resource type (see next line), and
(9) "st" is the stimulus resource type from p PICT, s sound, m movie, n none (ie present a clear screen or no sound), and you can also present text (without needing to create PICT files specifically) but using t for text here. You write the text that you wish to display in the file name field, and can specify the font, size, style and color using the "Stimulus Text" button at the top of the script editor window.
(10) "bg-file" and
(11) "st-file" are the file names of the background and stimulus files respectively, which must be in the same folder as the script, or the actual text to display for text trials.
There are 2 new optional fields added in version 2.1.6. These are "hShift" and "vShift" which allow you to offset pictures, movies or text from the default central position as set in the Preferences dialog Resources pane. These are also separated by tab chars. See the Bouncing Ball and Bouncing Text scripts for examples.
5. MacStim will check the script & preload before playing:
When the run button is clicked (or Run in the Control menu, or Command-/), the script will be parsed, looking for errors in syntax or incorrect file names. Resources will be loaded into memory to reduce disk access during the experiment. Insufficient RAM memory aborts the loading process only if it is not possible to create the minimum offscreen structures needed to run. Pictures and sounds can now be loaded during runtime (during the preceding trial) but this can slow presentation down so should be pre-flighted. A dialog box is presented when MacStim is ready to start the experiment (unless you request it to start immediately). Once you start it, by clicking OK, the dialog box will be dismissed, and for immediate and timed starts the cursor will be a flashing mouse awaiting a single mouse click. You can stop a running experiment at any time with Command-Period. If you choose the Preferences menu item (or use Command-Y), you can see many other options available. You can also try some of the example scripts (in the Samples folder) which show implementations of common experimental paradigms, and hopefully show solutions to some common questions.
For debugging purposes, you can select just a few contiguous lines and then the Run Selected Lines (or Command-1) menu item to play/run just those lines (be aware that if you select lines in the middle of a block and the rep time (repetition time for the whole block before cycling) in the top selected line is not more than 0 seconds, then the block will rapidly cycle probably without any stimuli being shown. (I've fallen for this too!)
6. MacStim has a Resource Finder:
Under the Control menu, is the Find Resources... item. This brings up a dialog box which you can use to specify the fields and resources, and MacStim will enter these directly onto the last line line of the script editor's text. To try this, click the "Open" button, navigate to the Samples folder, and click the "Use These" button. Then select your background and stimulus file names, timing options and stop event, and click "Enter" as many times as required, and "Done" when finished. You can do this to quickly add lines and then customize them individually in the script editor later.
7. MacStim will record responses:
To do this you need to uncheck the check box in the Experiments section of the Preferences dialog which is called Ignore Stop Events. This will mean that stop events (eg key presses or mouse clicks) will be watched for and will terminate the timing from onset of the stimulus (whose time is specified by the max interval). For consistency, the RT timing starts after the stimulus (whatever it is) is actually started. Note that for key events (ie if you specify that a key press should terminate the reaction time) MacStim will record the RT for the very first key press, but will keep recording key presses until the trial has ended. This means that you can record extra (perhaps random) key presses as well as design experiments in which the subject must press multiple sequences of keys. After the trial's total time has elapsed, MacStim will not record any more key events for that trial. If this is not clear then try out the example script called "Multiple keys example" in the Samples folder. For voice activated stop events (ie vox recording), MacStim can help you test the level of sound, the quality of recording and the disc space required using the Timing & Events pane of the Preferences dialog. You can thus save a sound file containing what actually triggered the recording and check whether it was the correct response etc. See the Preferences topic for details.
The rest of this information text contains more detail about how to operate MacStim, and other customizations. I suggest you use the Print All… menu item under this Help window's File menu (top left) to print all these help items out and read them whilst playing with MacStim's options & samples.
